feat: astro logger by ematipico · Pull Request #13787 · withastro/docs

ematipico · 2026-04-22T11:28:07Z

Description (required)

This PR adds documentation for the upcoming experimental logger. The RFC is here: withastro/roadmap#1339

Linear: AST-84

For Astro version: `6.2.0`. See astro PR #16437.

The attached PR is the one that mostly documents the new APIs

netlify · 2026-04-22T11:28:13Z

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	`4a21df6`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/69eb78fa0524920008052fb9
😎 Deploy Preview	https://deploy-preview-13787--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

astrobot-houston · 2026-04-22T11:28:37Z

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/reference/experimental-flags/logger.mdx	Localization added, will be marked as complete.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

ArmandPhilippot

Thanks Ema! I left a few suggestions mostly around:

docs style, consistency with other experimental pages
and some reorganization to make it easier to scan. For example I find the API block placement a bit annoying currently:

API block between the introductory sentence and the list

Also, I noticed you mentioned the AstroLoggerDestination but I don't think we document its exact shape at the moment. It would be helpful to have a "Types reference" section with the public types/types required to build a custom logger.

Then, when the feature becomes stable we only need to reorganize the contents, everything would already be here.

For example, the experimental Route caching has an API reference but we could also use the same format used in the other references (e.g. Renderer types).

ematipico · 2026-04-22T13:54:29Z

Also, I noticed you mentioned the AstroLoggerDestination but I don't think we document its exact shape at the moment. It would be helpful to have a "Types reference" section with the public types/types required to build a custom logger.

I was hoping to get some suggestions on where to have it, and if it needs an header

ArmandPhilippot · 2026-04-22T14:28:13Z

If there is only one useful type, a reference section might not be the best approach and we could reshape Custom loggers with something similar to session drivers:

(we don't necessarily need to show write(), etc. in the sidebar, this was just to show the hierarchy)

Otherwise, a new section at the end might be easier to organize the content. Each section only describe what is available and we add links to the relevant types for advanced users. This remains easy to scan without having to scroll too much for those not interested in building their own logger. Something like:

And we have precedents for both approaches, so the structure remains familiar to users.

Co-authored-by: Armand Philippot <git@armand.philippot.eu>

ematipico · 2026-04-24T14:07:18Z

Hey @ArmandPhilippot , I added more information to the page. Let me know what you think

ArmandPhilippot

Thanks for the updates, @ematipico !

I left a few suggestions, most of them try to shorten/simplify the wording or add links when we can. And one of them is pretty big: if we replace your list with sections, we can link to them directly when needed and this might be easier to scan.

Feel free to disagree. 😄 After that, it looks ready to me!

ArmandPhilippot · 2026-04-24T14:29:33Z

+
+### `logHandlers.compose`
+
+A particular function that allows using multiple loggers. The same message is broadcasted to all loggers. The function accepts an arbitrary number of logger configurations.logHandlers


I think your autocomplete function is playing tricks on us again (.logHandlers) 😄 But I think we can combine the first and last sentence:

Suggested change

A particular function that allows using multiple loggers. The same message is broadcasted to all loggers. The function accepts an arbitrary number of logger configurations.logHandlers

A particular function that allows configuring multiple loggers in an arbitrary order. The same message is broadcasted to all loggers.

ArmandPhilippot · 2026-04-24T14:34:31Z

+});
+```
+
+The following example implements a minimal logger returning an `AstroLoggerDestination` object with the required `write()` function:


Since we now have a link I think this could be helpful here:

Suggested change

The following example implements a minimal logger returning an `AstroLoggerDestination` object with the required `write()` function:

The following example implements a minimal logger returning an [`AstroLoggerDestination` object](#astrologgerdestination) with the required `write()` function:

ArmandPhilippot · 2026-04-24T14:45:15Z

+});
+```
+
+We will expose an utility form the `astro/logger` package to check the log level.


From the changeset, this is already available, and we avoid "we" 😄

Suggested change

We will expose an utility form the `astro/logger` package to check the log level.

The `astro/logger` package exposes a [`matchesLevel()`](#matcheslevel) helper to check the log level. This can be useful when [building a custom logger](#custom-loggers).

ArmandPhilippot · 2026-04-24T15:00:21Z

+This is the interface that custom loggers must implement. The following can be implemented:
+- `write(message: AstroLoggerMessage) => void`: a mandatory method that accepts a `AstroLoggerMessage`. It's called for every log.
+- `flush() => Promise<void> | void`: an optional function that is called at end of each request. Useful for advanced loggers for flushing logger messages while keeping the connection to the destination alive.
+- `close() => Promise<void> | void`: an optional function that is called before a server is shut down. This is a function usually called by adapters such as `@astrojs/node`. 


Nothing really wrong but:

with sections, this is easier to scan and this allows us to use links to these sections.

I simplified a bit some sentences (e.g. function that is called > function called) to make them look like definitions

Suggested change

This is the interface that custom loggers must implement. The following can be implemented:

- `write(message: AstroLoggerMessage) => void`: a mandatory method that accepts a `AstroLoggerMessage`. It's called for every log.

- `flush() => Promise<void> | void`: an optional function that is called at end of each request. Useful for advanced loggers for flushing logger messages while keeping the connection to the destination alive.

- `close() => Promise<void> | void`: an optional function that is called before a server is shut down. This is a function usually called by adapters such as `@astrojs/node`.

This is the interface that custom loggers must implement.

#### `AstroLoggerDestination.write()`



**Type:** `(message: AstroLoggerMessage) => void`



A mandatory method called for each log and accepting an [`AstroLoggerMessage`](#astrologgermessage).

#### `AstroLoggerDestination.flush()`



**Type:** `() => Promise<void> | void`



An optional function called at the end of each request. This is useful for advanced loggers that need to flush log messages while keeping the connection to the destination alive.

#### `AstroLoggerDestination.close()`



**Type:** `() => Promise<void> | void`



An optional function called before a server is shut down. This function is usually called by adapters such as `@astrojs/node`.

For the last sentence I hesitated to simplify it:

-An optional function called before a server is shut down. This function is usually called by adapters such as `@astrojs/node`. +An optional function called by adapters (e.g. `@astrojs/node`) before shutting down the server.

But maybe "usually" was intentional so I haven't updated that.

ArmandPhilippot · 2026-04-24T15:05:18Z

+
+### `AstroLoggerMessage`
+
+The incoming object from the `AstroLoggerDestination.write` function:


With the previous suggestion, we can now add a link here:

Suggested change

The incoming object from the `AstroLoggerDestination.write` function:

The incoming object from the [`AstroLoggerDestination.write()`](#astrologgerdestinationwrite) function:

ArmandPhilippot · 2026-04-24T15:06:53Z

+### `AstroLoggerMessage`
+


Is inlining the type useful here? I mean I noticed you specified that message is a string below and I see that label can be null

Suggested change

### `AstroLoggerMessage`

### `AstroLoggerMessage`



**Type:** `{ label: string | null; level: AstroLoggerLevel; message: string; newLine: boolean; }`

ArmandPhilippot · 2026-04-24T15:07:29Z

+### `AstroLoggerMessage`
+
+The incoming object from the `AstroLoggerDestination.write` function:
+- `message: string`: the message being logged.


If my previous suggestion makes sense we no longer need this and all items are consistent:

Suggested change

- `message: string`: the message being logged.

- `message`: the message being logged.

ArmandPhilippot · 2026-04-24T15:08:20Z

+
+### `matchesLevel`
+
+`matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel): boolean`


nit, formatting:

Suggested change

`matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel): boolean`



**Type:** `matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel) => boolean`

ArmandPhilippot · 2026-04-24T15:10:56Z

+
+`matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel): boolean`
+
+Given two [logger level](#log-level), it returns whether the first level matches the second level. 


Suggested change

Given two [logger level](#log-level), it returns whether the first level matches the second level.

Given two [log levels](#log-level), it returns whether the first level matches the second level.

feat: astro logger

0fd30f2

ematipico mentioned this pull request Apr 22, 2026

feat(logger): docs and runtime withastro/astro#16437

Merged

ArmandPhilippot reviewed Apr 22, 2026

View reviewed changes

ArmandPhilippot added this to the 6.2 milestone Apr 22, 2026

ematipico mentioned this pull request Apr 24, 2026

feat: experimental logger withastro/astro#16477

Open

ematipico and others added 3 commits April 24, 2026 13:43

Apply suggestions from code review

8f2f10c

Co-authored-by: Armand Philippot <git@armand.philippot.eu>

feedback

41999b4

feedback

4a21df6

ArmandPhilippot reviewed Apr 24, 2026

View reviewed changes


		### `logHandlers.compose`

		A particular function that allows using multiple loggers. The same message is broadcasted to all loggers. The function accepts an arbitrary number of logger configurations.logHandlers

	A particular function that allows using multiple loggers. The same message is broadcasted to all loggers. The function accepts an arbitrary number of logger configurations.logHandlers
	A particular function that allows configuring multiple loggers in an arbitrary order. The same message is broadcasted to all loggers.

	The following example implements a minimal logger returning an `AstroLoggerDestination` object with the required `write()` function:
	The following example implements a minimal logger returning an [`AstroLoggerDestination` object](#astrologgerdestination) with the required `write()` function:

	We will expose an utility form the `astro/logger` package to check the log level.
	The `astro/logger` package exposes a [`matchesLevel()`](#matcheslevel) helper to check the log level. This can be useful when [building a custom logger](#custom-loggers).

-This is the interface that custom loggers must implement. The following can be implemented:
-- `write(message: AstroLoggerMessage) => void`: a mandatory method that accepts a `AstroLoggerMessage`. It's called for every log.
-- `flush() => Promise<void> | void`: an optional function that is called at end of each request. Useful for advanced loggers for flushing logger messages while keeping the connection to the destination alive.
-- `close() => Promise<void> | void`: an optional function that is called before a server is shut down. This is a function usually called by adapters such as `@astrojs/node`.
+This is the interface that custom loggers must implement.
+#### `AstroLoggerDestination.write()`
+<p>
+**Type:** `(message: AstroLoggerMessage) => void`
+</p>
+A mandatory method called for each log and accepting an [`AstroLoggerMessage`](#astrologgermessage).
+#### `AstroLoggerDestination.flush()`
+<p>
+**Type:** `() => Promise<void> | void`
+</p>
+An optional function called at the end of each request. This is useful for advanced loggers that need to flush log messages while keeping the connection to the destination alive.
+#### `AstroLoggerDestination.close()`
+<p>
+**Type:** `() => Promise<void> | void`
+</p>
+An optional function called before a server is shut down. This function is usually called by adapters such as `@astrojs/node`.


		### `AstroLoggerMessage`

		The incoming object from the `AstroLoggerDestination.write` function:

	The incoming object from the `AstroLoggerDestination.write` function:
	The incoming object from the [`AstroLoggerDestination.write()`](#astrologgerdestinationwrite) function:

	- `message: string`: the message being logged.
	- `message`: the message being logged.


		### `matchesLevel`

		`matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel): boolean`


		`matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel): boolean`

		Given two [logger level](#log-level), it returns whether the first level matches the second level.

	Given two [logger level](#log-level), it returns whether the first level matches the second level.
	Given two [log levels](#log-level), it returns whether the first level matches the second level.

Uh oh!

Conversation

ematipico commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description (required)

For Astro version: 6.2.0. See astro PR #16437.

Uh oh!

netlify Bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

astrobot-houston commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ematipico commented Apr 22, 2026

Uh oh!

ArmandPhilippot commented Apr 22, 2026

Uh oh!

ematipico commented Apr 24, 2026

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ematipico commented Apr 22, 2026 •

edited

Loading

For Astro version: `6.2.0`. See astro PR #16437.

netlify Bot commented Apr 22, 2026 •

edited

Loading

astrobot-houston commented Apr 22, 2026 •

edited

Loading